External Systems

KickStartTrustee Basic FMIS

KickStartTrustee Basic FMIS is a basic FMIS (Farm Management Information system) that serves as a demo to illustrate the envisioned interaction between an Agricultural Data Trustee and an agricultural third-party application. KST Basic FMIS is realized as a Single Page Application (SPA) for farmers and has no backend. Farmers can use KST Basic FMIS to manage their field-related data stored at the KST Platform. KST Basic FMIS can provide and consume the field-related data of the farmer. Thus, KST Basic FMIS plays the role of a Data Prosumer that interacts with KST Platform (see System Context and Domain).

Helpful Links

• The source code of KST Basic FMIS can be found in this GIT repository (in the example-farming-trustee branch): Git Repository

Features

KST Basic FMIS has a simple dashboard that offers the following (basic) features/ capabilities to the farmer:

1. Provides the farmer with the ability to create a field and add its metadata (e.g., name, location, etc.,) and pushes (acts as a data provider) the field to be stored at the farmer’s account on KST Platform.
2. Provides the farmer with the ability to create a disease report for their fields, and pushes (acts as a data provider) the report to be stored at the farmer’s account on the KST Platform.
3. Retrieves (acts as a data consumer) the farmer’s list of fields from their account on the KST Platform, and displays them in a list view as well as in a map view (simple map and satellite).
4. Retrieves (acts as a data consumer) the farmer’s list of disease reports from their account on the KST Platform, and displays the details in a list view.
5. Retrieves (acts as a data consumer) the farmer’s list of disease warnings from their account on the KST Platform, and displays the details in a list view.

General Information

KST Platform offers a web API for third-party applications. The API covers the following concerns: data provisioning, data consumption and consent management. The API is protected using Access Tokens according to OAuth 2.0 standard.

KST Basic FMIS is registered as a client to the KST Platform Authorization Server. To obtain an Access Token, KST Basic FMIS performs the Authorization Code Flow with the farmer. With that Access Token, KST Basic FMIS can use the KST Platform API.

Providing and Consuming data via KST Platform requires explicit consent of the farmer who is considered as the “owner” of its field-related data. Therefore, in case there is no consent yet, KST Basic FMIS will request the consent of the farmer using the consent request mechanism provided by KST Platform. Via KST Platform UI, the farmer will be able to review the consent request and decide whether to accept or decline it. Once the consent request is accepted, i.e., the consent has been established, KST Basic FMIS will be able to provide and consume farmer’s data using KST Platform according to the farmer’s consent.

Core Concepts and Technology

Core Concepts

• KST Basic FMIS is a Data Prosumer that provides data to and consumes data from the KST Platform.
  • Rationale: KST Platform is envisioned as the central place to store/ manage the farmer’s data and who is allowed to access it (i.e., reading/ consuming existing data as well as writing /providing new data). KST Basic FMIS is one system of possibly many that will provide data to or consume data from the KST Platform according to the consents of the farmer.
• KST Basic FMIS is implemented as a Single Page Application (SPA)
  • Rationale: With KST Basic FMIS we want to explore and demonstrate how a third-party application can connect to the KST Platform. Building a SPA is one simple way to implement a simple prototype of such an application. Furthermore, the development team is familiar with SPAs.
• KST Basic FMIS uses the OAuth2 Authorization Code Flow and Access Tokens
  • Rationale: KST Platform uses OAuth2 and according access tokens to secure its API. To communicate with the KST Platform API, KST Basic FMIS needs to get and use such access tokens. We decided to use the Authorization Code Flow as the Authorization Code Flow is the recommended flow for SPA.

Technology

• Typescript: A programming language.
  • Rationale: The development team prefers Typescript over plain JavaScript because of the better IDE support (warnings, code completion).
• React: A Front-end JavaScript library for building user interfaces.
  • Rationale: It is the state of the Art Technology for SPAs (Single Page Applications), and the development team is familiar with React.
• Material UI: An open-source React component library that implements Google’s Material Design.
  • Rationale: It offers a comprehensive nice looking easy to use set of components and has typescript support out of the box.
• MUI X (https://github.com/mui/mui-x): We used the Data Grid and Date and Time Pickers.
  • Rationale: It fits well to the material-ui library.
• React Intl: A library that supports internationalization for React applications.
  • Rationale: It enables the support of multiple natural languages in SPAs.
• React Router: A JavaScript framework that supports in handling client and server-side routing in React applications.
  • Rationale: It allows bookmarks and having stable urls for our SPA.
• Leaflet: A JavaScript library for interactive maps.
  • Rationale: The development team used the technology in other projects and were familiar with it.
  • Used Plugins:
    • Leaflet Geoman Free: A Leaflet plugin for creating and editing geometry layers.
    • Leaflet Control Geocoder: A geocoder form to locate places (https://github.com/perliedman/leaflet-control-geocoder).
    • React-Leaflet: A set of React components to integrate Leaflet maps in React applications.
• Keycloak JS (https://www.npmjs.com/package/keycloak-js): A client-side JavaScript OpenID Connect library that can be used to secure web applications.
  • Rationale: Keycloak JS is provided by the keycloak open source project, and thus, it works perfectly together with keycloak.
• openapi-generator: A tool that automatically generates API client libraries (SDK generation), server stubs, documentation and configuration given an OpenAPI Spec (v2, v3).
  • Rationale: It works good with the openapi specifications created by springdoc to generate the API client libraries.
• npm: A package manager.
• GitLab CI/CD: GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset (CI/CD).
  • Rationale: It is easy to use, provide a better developer experience, faster commit-to-release, offered by the used version control system (GitLab).
• Renovate Bot: A tool that regularly scans the Git repositories for outdated dependencies and automatically creates merge requests for the available version updates.
  • Rationale: It provides good support to keep the dependencies up-to-date.
• Docker: A containarization tool.
  • Rationale: It is the state of the Art technology to bundle and operate server side applications.
• lighttpd: A web server software.
  • Rationale: It is a very lightweight and fast web-server for static content.

Deployment/ Operations

KST Basic FMIS is containerized and can be operated using Docker. For details about the Deployment of our demo system as a whole (including KST Basic FMIS), please have a look at this page: Deployment and Operation.

The KST Basic FMIS Docker Image requires certain environment variables to be configured:

• KEYCLOAK_BASE_URL: The base url of the Keycloak instance that will be used for user sign-in and to retrieve access tokens (e.g., “https://auth.example.de”).
• KEYCLOAK_REALM: The Keycloak realm that will be used (e.g., “master”).
• KEYCLOAK_CLIENT_ID: The clientId for the KST Basic FMIS configured in Keycloak (e.g., “basic-fmis”).
• KST_API_BASE_PATH: API Base Path of the KST Platform instance that the KST Basic FMIS should connect to (e.g., “https://demo.example.de/api”)
• KST_OWNER_UI: Url of the KST Owner UI, used to redirect the farmer to the owner UI to review/process consent requests (e.g., “https://demo.example.de/owner/”).

Known Issues/ Limitations

KST Basic FMIS:

• Offers support for German and English languages. The user can change the language via a button in the _KST Basic FMIS._ However, the validation messages displayed by the Browser (for example if leaving a required form field empty) will not consider the user’s language choice in the application. Instead, the Browser Language Setting will determine the language used to display the validation message. As a result, it could be that a German hint is displayed by the Browser when using the app in English or the other way around. Thus, for a better experience, one should make sure to configure the Browser Language Setting in a suitable way to not be surprised by hints in a different language.
• Is implemented as a Single Page Application without a dedicated backend (KST Basic FMIS connects directly to the KST Platform API). Therefore, it runs only in the browser of the user (i.e., the farmer) and only as long as the website is opened.